Shareware Overload Trio 2

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Overload Trio 2 / Shareware Overload Trio Volume 2 (Chestnut CD-ROM).ISO / dir38 / grabb397.zip / DOCFILES.SFX / GRTXT.DOC < prev next >

Wrap

Text File | 1994-05-14 | 26KB | 535 lines

GRABBER/TXT(tm) The Text Screen Capture Program for MS-DOS and IBM-PC Compatibles Version 2.00 Shareware Issue ---------------------------------- DOCUMENTATION May 14, 1994 Copyright 1987-1994 by Gerald A. Monroe All rights reserved. +-------------------------------------------------+ | Although they are shareware, GRTXT and this | | documentation file are copyrighted. They are | | not in the public domain and they are not | | "freeware." Please consult page 6 of the | | REGISTER.DOC file for important copyright | | information and license provisions. | +-------------------------------------------------+ Thank you for your interest in the GRABBER(tm) screen capture system! The GRABBER package is being marketed in this special form as shareware. This means you have the opportunity to use and evaluate it for 30 days before you decide whether to buy. If you continue to use GRABBER.EXE, any of its "offspring" programs, or any of the other programs in the GRABBER package beyond such 30-day period, then you are required to send your registration fee to the publisher according to the instructions in the REGISTER.DOC file. When you register, you will receive a copy of the latest release of the registered GRABBER package that you order. You may not continue using GRABBER beyond such 30-day period without regis- tering. For registration instructions and a complete statement of your license to use this software, please consult the REGISTER.DOC file. Gerald A. Monroe P.O. Box 770906 Cleveland, Ohio 44107, U.S.A. CompuServe Mail: 72321,1257 Fax: (216) 521-6060 IBM, PC and PC/XT are trademarks of International Business Machines Corporation. Table of Contents Shareware Registration and License Information ..... 1 Overview of GRABBER/TXT ............................ 3 Using GRABBER and GRTXT simultaneously ............. 3 GRTXT doesn't work with graphics screens ........... 4 Modifying the GRTXT hotkey ......................... 4 GRTXT installation options, including the following: * DEFAULTDRIVE * MOUSE and NOMOUSE * UNLOAD * SOUND and NOSOUND * PROMPT and NOPROMPT * NOSWAP * NOEMS * NOUMB * INT=nn * INT=OFF * BATCHCAPTURE * BATCHCAPTURE:filename ......................... 4 Additional GRTXT configuration options ............. 5 * CROP and NOCROP ............................... 5 * 1FORM, 2FORM, 3FORM, 4FORM, 5FORM, NOFORM ..... 5 * PERMANENT=filename NOPERMANENT ................................... 6 * APPEND and NOAPPEND ........................... 7 How GRTXT names files .............................. 7 GRTXT and filename prompts ......................... 8 How to control GRTXT's "crop box" .................. 9 Calling GRTXT from your own programs ............... 10 GRTXT(tm) Documentation Page 3 of 10 OVERVIEW OF GRABBER/TXT ------------------------ GRABBER/TXT ("GRTXT") is an alternative version of the GRABBER screen capture program. It is an especially valuable tool for users who need to capture character-based text images from the video screen directly to plain ASCII text files on disk. While GRABBER can be used to capture both character-based text screens as well as pixel-based graphic images to your disk in the form of executable image files, GRTXT is designed to capture character-based text screens exclusively. GRTXT also differs from GRABBER in that GRTXT captures your screens directly to plain-ASCII text files, instead of to GRABBER's .exe file format. If your screen capture needs are mostly text-based, and you require the ASCII format rather than the .exe format, then GRTXT can be more convenient to use than GRABBER. GRTXT creates ASCII text files that are ready to use immediately, without having to be processed first by the GR2ASCII conversion utility which accompanies GRABBER. GRTXT is installed and operated in much the same way as GRABBER, and the two programs have a very similar look and feel. For the most part, this documentation for GRTXT covers only the aspects of GRTXT which differ from GRABBER. It is assumed here that you have read the GRABBER documentation file (GRABBER.DOC) and become familiar with that program's operation. USING GRABBER and GRTXT SIMULTANEOUSLY --------------------------------------- GRTXT is designed to be compatible with GRABBER. Both programs can be installed in memory and used at the same time, but only if you specify the "INT=OFF" command-line switch when you initial install GRTXT in memory. The default "hotkey" sequence for GRTXT is [Alt =]. That is, you hold down the [Alt] key, press the equal sign key [=], then release the [Alt] key. As in GRABBER, the MOUSE command-line option in GRTXT allows you to capture the screen by holding down the left and right mouse buttons simultaneously for one or two seconds. If you have installed both GRABBER.EXE and GRTXT.EXE in memory simultaneous- ly, you should not use the MOUSE switch to enable the mouse hotkey with both programs. Strange results are almost guaranteed to occur, and it may even lock up your computer when you use the mouse hotkey. It is acceptable to use the MOUSE switch with either GRTXT or GRABBER, but not both. GRTXT(tm) Documentation Page 4 of 10 GRTXT DOES NOT WORK WITH GRAPHICS SCREENS ------------------------------------------ GRTXT is designed to capture character-based text images exclu- sively. If you press GRTXT's hotkey and hear a single low- pitched tone on the computer speaker, this means that GRTXT thinks the video screen is running in a pixel-based graphics mode, and it is unable to capture the screen. Even if a pixel- based graphic image contains text characters, GRTXT will not attempt to "recognize" the outlines of the characters. MODIFYING THE GRTXT HOTKEY --------------------------- GRTXT allows you to modify your hotkey sequence from the default [Alt =] to practically any other key sequence you choose. In this respect, GRTXT is exactly like GRABBER. There is no sepa- rate documentation here which covers the procedure for changing your GRTXT hotkey. GRTXT uses the exact same hotkey procedures as GRABBER. You can read about these in the GRABBER.DOC manual, at page 33 and at Appendices A and B. (To view a list of valid KEY= codes for GRTXT, use the command GRTXT KEY=?. To view a list of valid SHIFT= codes, enter GRTXT SHIFT=?.) GRTXT COMMAND-LINE OPTIONS --------------------------- GRTXT accepts the following command-line configuration options. Each of these optional switches can be added to the GRTXT command line to alter GRTXT's default mode of operation. All of these switches are also available in the GRABBER.EXE program, and none is separately described here. For complete details concerning the purpose of these options and how they work, consult the section "Grabber Installation Options" beginning on page 14 in the GRABBER program documentation. * DEFAULTDRIVE (specifies capture destination) * MOUSE and NOMOUSE (enables/disables mouse hotkey) * UNLOAD (removes GRTXT from memory) * SOUND and NOSOUND (enables/disables sounds) * PROMPT and NOPROMPT (enables/disables screen prompts) * NOSWAP (disables swapping of DOS kernel) * NOEMS (disables GRTXT's EMS memory usage) * NOUMB (disables GRTXT'S UMB memory usage) * INT=nn (specifies block of interrupt vectors for redirecting IRQ0-IRQ7) * INT=OFF (disables redirection of IRQ0-IRQ7) * BATCHCAPTURE (causes immediate screen capture) * BATCHCAPTURE:filename (causes immediate screen capture to file specified as "filename") GRTXT(tm) Documentation Page 5 of 10 ADDITIONAL GRTXT CONFIGURATION OPTIONS --------------------------------------- In addition to the command-line configuration options above (which GRTXT.EXE shares with GRABBER.EXE), GRTXT also recognizes the following command-line options. Note that you may specify any of the following options on the GRTXT command line when you initially install GRTXT in memory, *or* after GRTXT is already resident in memory. Option: CROP or NOCROP Purpose: To enable or disable GRTXT's "crop box" feature, which allows you to capture only the part of the screen which you select. When the CROP setting is active and you request a screen capture, GRTXT does not capture the screen right away. Instead, it first prompts you to indicate which portion of the screen you wish to cap- ture to a .TXT file by drawing a box on top of the current screen image, which you can move and reshape to your preference. Instructions for moving and reshaping this "crop box" are given below on page 9. When the NOCROP setting is active, GRTXT captures the entire screen image to a .TXT file, and does not prompt you to indicate which portion you wish to capture. The default setting for this feature is NOCROP. Option: 1FORM, 2FORM, 3FORM, 4FORM, 5FORM, or NOFORM Purpose: To enable or disable GRTXT's ability to insert a "form feed" character after a specified number of screens has been captured to a .TXT file. This option only has an effect in the following situations: 1) The NOPROMPT setting and the APPEND setting are both active, or 2) The PROMPT setting is active and you are appending subsequent screen captures to the same .TXT file. Using these options, you can tell GRTXT to insert a form feed character (12 decimal, 0C hexadecimal) after 'n' screens have been captured to the same .TXT file, where 'n' can be any single digit from 1 to 5. For example, when the 1FORM setting is active, GRTXT in- serts a form feed character after each screen is writ- ten to the .TXT file. When the 2FORM setting is ac- GRTXT(tm) Documentation Page 6 of 10 tive, GRTXT inserts a form feed character after every second screen written to the .TXT file, and so forth. To prevent GRTXT from inserting any form feed charac- ters into the .TXT file, specify the NOFORM setting. Inserting form feed characters can be useful for print- ing the data in the captured .TXT file later, because the form feed character causes most standard (non- Postscript) printers to automatically eject the current page and start a new page at the point where the char- acter appears. The default setting for this feature is NOFORM. Options: PERMANENT=filename NOPERMANENT Purpose: To tell GRTXT whether to capture all screens to the file represented by "filename". This option allows you to force GRTXT to capture all screen data to a certain filename that you specify. For example, to capture all screens to a file in the current directory called TEXTDATA.TXT, you would in- clude this option on the GRTXT command line: GRTXT [other options] PERMANENT=TEXTDATA.TXT Your "filename" can also include a drive and path specification, for example: GRTXT [other options] PERMANENT=C:\PICTURES\TEST.TXT If you have told GRTXT to capture all data to a certain filename using the "PERMANENT=" option, you can tell it to stop forcing data into that file by including the NOPERMANENT option on the command line. Note that when you use the "PERMANENT=" option, it automatically has two side effects. First, PERMANENT= automatically sets the NOPROMPT option, which means you will not be prompted on the screen to enter a filename each time you request a screen capture. Second, PERMA- NENT= automatically sets the APPEND option (see below), which means that all screen data will be appended to the same .TXT file while the PERMANENT= setting is active. The default setting for this feature is NOPERMANENT. GRTXT(tm) Documentation Page 7 of 10 Option: APPEND or NOAPPEND Purpose: To enable or disable the "Append Mode" when you have told GRTXT not to use on-screen filename prompts by using the NOPROMPT command switch. This option has no effect when the filename prompts are enabled. When filename prompts are disabled and you specify APPEND, then GRTXT will create only one .TXT file, and will append the contents of each subsequent screen to that file until you enable the filename prompts again. When filename prompts are disabled and you specify NOAPPEND, then GRTXT works in its "Overwrite" mode, which means that it will create a separate .TXT file for each screen capture you request. The default setting for this feature is NOAPPEND. HOW GRTXT NAMES FILES ---------------------- When the PROMPT setting is active, GRTXT prompts you on the screen to enter a name for the captured .TXT file. However, when the NOPROMPT setting is active, GRTXT does not prompt you to enter a filename. Instead, it makes its own filename as follows. GRTXT tries to automatically detect the name of the program that is running when you tell it to capture the screen. If GRTXT is able to detect the program's name, it takes the first six charac- ters of that name and adds (1) a two-digit number from "00" through "99", and (2) a file name extension of ".TXT". This is the name that will be assigned to the captured screen file. GRTXT always picks the lowest available two-digit number in the destination path. For example, if you are running a program called "WORDPROC.EXE" and there are already four files in the destination path named "WORDPR00.TXT" through "WORDPR03.TXT", then your next screen capture from that program will be called "WORDPR04.TXT". If there are already 100 files in the destina- tion path named "WORDPR00.TXT" through "WORDPR99.TXT", then your next screen capture from that program will be called "WORDPR00.TXT", and the contents of the original WORDPR00.TXT file will be overwritten and lost forever. If GRTXT detects that you are sitting at the DOS prompt when you request a screen capture, it will name the captured files MSDOS00.TXT, MSDOS01.TXT, and so forth. If GRTXT is unable to detect the name of the currently running program, it will assign the names SCREEN00.TXT, SCREEN01.TXT, and so forth. GRTXT(tm) Documentation Page 8 of 10 GRTXT AND FILENAME PROMPTS --------------------------- Probably the most significant difference you will notice between GRTXT's interface and GRABBER's is in the area of the on-screen filename prompts. The following discussion only applies when the PROMPT setting is active. The first time you call up GRTXT after installing it, there is no default filename shown on the screen. You must supply your own file name. After your first .TXT screen capture, however, subsequent file- name prompts will offer you a default filename which is identical to the previous one you specified. You may accept this default filename by pressing <Return>, or you can enter another name. After you press <Return>, you will then see this additional prompt, which is not present in GRABBER: FILENAME exists -- (A)ppend, (O)verwrite, (C)ancel ? If you wish to retain the contents of FILENAME.TXT and simply append the current screen to the bottom of it, just press <A> or <Return>. If you wish to overwrite (i.e., erase and replace) the contents of the original FILENAME.TXT file, then press <O>. If you decide not to work with this name and wish to enter a differ- ent name instead, press <C> (for "Cancel"). GRTXT(tm) Documentation Page 9 of 10 HOW TO CONTROL GRTXT's CROP BOX -------------------------------- When the CROP option is enabled (see page 5 above), you can move and reshape GRTXT's crop box on your screen by using the following keys: <Esc> . . . . . . . . . . Abort the screen capture and exit back to the foreground program. <Return> . . . . . . . . Accept the area covered by the crop box, and begin capturing. <Left Arrow>, <Right Arrow>, <Up Arrow> or <Down Arrow> . . . . . . Move the crop box in the direction indicated, without changing the shape of the box. <Shift><Left Arrow> . . . Shrink the box horizontally. <Shift><Right Arrow> . . Expand the box horizontally. <Shift><Up Arrow> . . . . Shrink the box vertically. <Shift><Down Arrow> . . . Expand the box vertically. <Home> . . . . . . . . . Move the box to the upper left-hand corner of the screen. <End> . . . . . . . . . . Move the box to the lower left-hand corner of the screen. <Ctrl><PgUp> . . . . . . Move the box to the upper right- hand corner of the screen. <Ctrl><PgDn> . . . . . . Move the box to the lower right- hand corner of the screen. <PgUp> . . . . . . . . . Move box to top edge of the screen. <PgDn> . . . . . . . . . Move box to bottom edge of the screen. <Ctrl><Left Arrow> . . . Move box to left edge of the screen. <Ctrl><Right Arrow> . . . Move box to right edge of the screen. GRTXT(tm) Documentation Page 10 of 10 PROGRAMMERS NOTE: CALLING GRTXT FROM YOUR OWN PROGRAMS ------------------------------------- If you are a programmer developing your own software, you can invoke GRTXT to capture the screen from within your own program, assuming that GRTXT is already resident in memory. This is accomplished by using GRTXT's external programming hook, which is really a customized call to Interrupt 16h, described below. You can write a routine to implement this hook in 80x86 assembly language or in any high-level programming language which supports BIOS-level interrupt calls. CUSTOMIZED INTERRUPT 16H TO INVOKE GRTXT, SERVICE 4754H -------------------------------------------------------- On entry: AX = 4754h DL = 0 (to check only if GRTXT is resident) DL = 1 (to capture the current screen) On return: AX = 5447h (if GRTXT is installed in memory) For DL=0 or DL=1: BL contains the logical drive to which the capture would be attempted (DL=0) or was attempted (DL=1). 0=default drive, 1=drive A, 2=drive B, and so forth. For DL=1: No --> Capture successful. ES:DX points to Carry an ASCIIZ string which contains the Flag [drive:][\path\]filename of the newly created offspring (drive also coded in BL). Carry --> If DX = FFFFh, then a capture attempt Flag failed due to a critical disk error or Set disk-full error on the logical drive encoded in BL. (Speaker beeped in either case.) If DX does not equal FFFFh, capture was not attempted. GRTXT was busy servicing a prior capture request, or some other disk I/O was occurring, or DOS was not in a re- enterable state. Try again momentarily. * * * End of GRTXT.DOC * * *